Context Clearing by kemerava · Pull Request #1379 · finos/FDC3

kemerava · 2024-09-27T18:37:37Z

Adding context cleaning

netlify · 2024-09-27T18:37:54Z

✅ Deploy Preview for fdc3 ready!

Name	Link
🔨 Latest commit	`a7e5c4b`
🔍 Latest deploy log	https://app.netlify.com/projects/fdc3/deploys/6883d673a522e200081a074a
😎 Deploy Preview	https://deploy-preview-1379.preview-fdc3.finos.org
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

kriswest · 2024-10-01T13:40:28Z

docs/api/ref/Channel.md

  broadcast(context: Context): Promise<void>;
  getCurrentContext(contextType?: string): Promise<Context|null>;
  addContextListener(contextType: string | null, handler: ContextHandler): Promise<Listener>;
+  clearContext(contextType?: string): Promise<void>;


I'm wondering if we should require an explicit null argument (contextType: string | null) to clear all types - which would match addContectListener or stick with this (matching getCurrentContext). Either works of course.

To me it makes sense to keep it closer to getCurrentContext, because they seem most related to me, but happy to hear any thoughts/suggestions.

There is a historical reason for addContextListener having an explicit null argument, the contextType argument was originally optional so the handler argument could be either first or second (when a type was specified). This was NOT good in practice so we moved to an explicit null argument and deprecated the single argument override:
https://fdc3.finos.org/docs/2.0/api/ref/DesktopAgent#addcontextlistener-deprecated

We don't have that problem here, so I agree its fine as is (matching getCurrentContext).

docs/api/ref/Channel.md

kriswest

Many thanks for taking this on @kemerava.

Could you add an entry to the CHANGLOG.md file please.

I think we should keep this open until after fdc3 for the web (#1191) is merged, when we will need to add schemas for a request and response message. The same may be needed in the bridging (the fdc3.nothing ewill propagate through normal broadcast messages, but I think this will need a specific message to indicate it happened through the clearContextAPI call).

docs/api/spec.md

schemas/context/nothing.schema.json

src/api/Channel.ts

Co-authored-by: Kris West <kris.west@interop.io>

kriswest

LGTM - although we could do with an example of listening for cleared context somewhere.

Holding approval until after fdc3-for-web is merged as we'll then need to add schemas to support it there. Bridging schemas are also needed, those should be added before this is merged.

Many thanks for the contribution @kemerava, much appreciated.

kemerava · 2024-12-13T13:44:51Z

@kriswest could you please take a look at the conformance tests that I added? Thanks

kriswest

Thanks for adding the conformance test cases! I think we'llneed a couple f additional cases that look the effect on user channels.

toolbox/fdc3-conformance/App-Channel-Tests.md

kriswest · 2024-12-13T14:20:14Z

toolbox/fdc3-conformance/App-Channel-Tests.md

 - `ACContextHistoryLast`: In step 5. **A** retrieves the _untyped_ current context of the channel via `const currentContext = await testChannel.getCurrentContext()`. Ensure that A receives only the very last broadcast context item _of any type_.
+- `ACClearHistorySpecificContext`: Perform the above test, except after step 3 clear context with `await testChannel.clearContext('fdc3.instrument')`. Ensure that in step 5 nothing is received for `const instrument = await testChannel.getCurrentContext('fdc3.instrument')` and context is received successfully for `const instrument = await testChannel.getCurrentContext('fdc3.contact')`
+- `ACClearHistoryAllContexts`: Perform the above test, except after step 3 clear context with `await testChannel.clearContext('fdc3.nothing')`. Ensure that in step 5 nothing is received for `const instrument = await testChannel.getCurrentContext('fdc3.instrument')` and for `const instrument = await testChannel.getCurrentContext('fdc3.contact')`
+- `ACClearHistoryAllContextsSubscribedToNothing`: Perform the above test, except after step 3 clear context with `await testChannel.clearContext('fdc3.nothing')` and in step 4 call `await testChannel.addContextListener("fdc3.nothing", handler)` instead. Ensure that after clearing context, the handler is called. 


A few thoughts on this case:

I think you want to clear fdc3.instrument or all types (null) rather than fdc3.nothing

As written, the nothing handler is added after calling clear, in that case it won't receive anything on an app channel. The handler needs to be in place before the clear.

I think this needs to be 2 cases, one for clearing all types and another for a specific type that confirms the other is not affected and that the fdc3.nothing quotes the correct type.

Finally, I think we need at least one case that checks the behavior of user channele- you'll work with the channel as an app channel to clear it (either retrrieving it by name, via getUserChannels, or getCUrrentChannel) but we should also confirm that it gets the fdc3.nothing broadcast and that it doesn't retain the cleared context.

Co-authored-by: Kris West <kris.west@interop.io>

kriswest · 2025-04-17T15:34:08Z

/netlify

kriswest · 2025-04-17T15:37:28Z

@kemerava, @robmoffat and I were talking about this recently and wondering if we should rethink the fdc3.nothing use and instead go with events... We could bring addEventListener to Channel (currently only in PrivateChannel and allow aps to listen for context clearing events (on the DA for the current user channel on the channel object for specific channels). I think the fdc3.nothing use is probably the weakest or most awkward part of the proposal (particularly if someone broadcasts fdc3.nothing from an app).

WDYT?

kemerava · 2025-05-08T18:29:55Z

@kemerava, @robmoffat and I were talking about this recently and wondering if we should rethink the fdc3.nothing use and instead go with events... We could bring addEventListener to Channel (currently only in PrivateChannel and allow aps to listen for context clearing events (on the DA for the current user channel on the channel object for specific channels). I think the fdc3.nothing use is probably the weakest or most awkward part of the proposal (particularly if someone broadcasts fdc3.nothing from an app).

WDYT?

@kriswest @robmoffat updated based on what I understood the logic would be. Please let me know if I need to change something else or if I misunderstood your suggestion

I see I still have to fix some of the build errors too

Copilot

Pull Request Overview

Adds a new clearContext API to channels, updates schemas and reference docs to support context-cleared events, and extends conformance tests for the new behavior.

Introduce clearContext method and contextCleared event in Channel API and implementation
Update JSON schemas and agent protocol to include clearContext request/response
Enhance documentation and conformance tests for context-clearing scenarios

Reviewed Changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
website/versioned_docs/version-2.0/api/conformance/App-Channel-Tests.md	Add versioned tests for clearing specific/all contexts
website/static/schemas/2.2/api/agentResponse.schema.json	Register `clearContextResponse` in agentResponse enum
website/docs/api/spec.md	Document `clearContext` behavior and fdc3.nothing subtype field
website/docs/api/ref/Events.md	Define `contextCleared` event in TS and .NET
website/docs/api/ref/Channel.md	Add `clearContext` and `addEventListener` to Channel interface
website/docs/api/conformance/App-Channel-Tests.md	Add conformance scenarios and test IDs for context clearing
packages/fdc3-standard/src/api/Events.ts	Add `FDC3ContextClearedEvent` TypeScript interface
packages/fdc3-standard/src/api/Channel.ts	Implement `clearContext` and `addEventListener` in Channel API
packages/fdc3-schema/schemas/api/clearContextResponse.schema.json	New JSON schema for clearContextResponse
packages/fdc3-schema/schemas/api/clearContextRequest.schema.json	New JSON schema for clearContextRequest
packages/fdc3-schema/schemas/api/appRequest.schema.json	Include `clearContextRequest` in appRequest schema
packages/fdc3-schema/schemas/api/agentResponse.schema.json	Include `clearContextResponse` in agentResponse schema
packages/fdc3-agent-proxy/src/channels/DefaultChannel.ts	Proxy `clearContext` and event listener to agent via messaging
CHANGELOG.md	Note addition of `clearContext` API and issue resolutions

Comments suppressed due to low confidence (3)

website/docs/api/spec.md:259

The documentation refers to a subType field, but the actual property in events and contexts is named contextType. Update this to match the implementation.

To raise an intent without a context, use the [`fdc3.nothing`](../context/ref/Nothing) context type. This type exists so that applications can explicitly declare that they support raising an intent without a context (when registering an `IntentHandler` or in an App Directory). This type is also used when the context is cleared for the channel. If the optional context type is provided when performing [`clearContext`](ref/Channel.md#clearcontext), that type will be recorded in the field `subType` of [`fdc3.nothing`](../context/ref/Nothing) context type.

website/docs/api/ref/Events.md:248

In the TypeScript definition for FDC3ContextClearedEvent, the details property should use contextType instead of type to align with other language bindings and the schema.

    type: string | null;

website/docs/api/conformance/App-Channel-Tests.md:77

[nitpick] The test IDs ACClearContext1 and ACClearContext2 are inconsistent with the earlier ACClearHistory* naming. Consider renaming them to match the existing prefix scheme.

- `ACClearContext1`: Perform above test.

Copilot · 2025-07-09T13:39:51Z

website/docs/api/ref/Events.md

+public class Fdc3ContextClearedEvent : Fdc3Event
+{
+    public Fdc3ContextClearedEvent(string? contextType)
+        : base(Fdc3EventType.ContextCleared, new Fdc3ContextClearedEvent(contextType))


The .NET constructor is recursively instantiating Fdc3ContextClearedEvent instead of passing a details object. It should pass a Fdc3ContextClearedEventDetails instance to the base constructor.

Suggested change

: base(Fdc3EventType.ContextCleared, new Fdc3ContextClearedEvent(contextType))

: base(Fdc3EventType.ContextCleared, new Fdc3ContextClearedEventDetails(contextType))

Copilot · 2025-07-09T13:39:51Z

packages/fdc3-agent-proxy/src/channels/DefaultChannel.ts

+    switch (type) {
+      case 'contextCleared':
+        listener = new EventListener(this.messaging, 'contextCleared', handler);
+        break;


The addEventListener implementation throws on null event type, but the API allows subscribing to all events with null. Consider handling null to register a listener for all event types.

Suggested change

break;

break;

case null:

listener = new EventListener(this.messaging, 'allEvents', handler); // Register for all events

break;

Copilot has a point there. It looks like this is also wrong where we listener for the channelChanged event:

FDC3/packages/fdc3-agent-proxy/src/DesktopAgentProxy.ts

Lines 77 to 85 in d4a261a

addEventListener(type: FDC3EventTypes | null, handler: EventHandler): Promise<Listener> {

switch (type) {

case 'userChannelChanged':

return this.channels.addChannelChangedEventHandler(handler);

default:

Logger.warn(`Tried to add a listener for an unknown event type: ${type}`);

return Promise.reject(new Error('UnknownEventType'));

}

}

Co-pilot's suggestion to fix isn't right however. Rather EventListener will probbably ned to be adjusted to be able to take multiple types:

FDC3/packages/fdc3-agent-proxy/src/listeners/EventListener.ts

Line 12 in d4a261a

constructor(messaging: Messaging, type: string, handler: EventHandler) {

As we need to know the specific messages it should respond to (from a set that is wider than the scope of the listener).

Copilot · 2025-07-09T13:39:52Z

website/docs/api/ref/Channel.md

+</Tabs>
+
+Used to clear the specified context type if provided, otherwise, clear all context types present in the channel. The Desktop Agent MUST update its internal representation of the context in the channel and ensure that subsequent calls to [`getCurrentContext`](#getcurrentcontext) and any new joiners to that channel (through [`joinUserChannel`](DesktopAgent#joinUserChannel) or [`addContextListener`](DesktopAgent#addContextListener)) will not receive anything for either specified context type or the most recent context until new context has been broadcast to the channel. 
+Desktop Agents MUST also immediately notified the apps that are listening to `contextCleared` event for this channel. If a `contextType` parameter was provided, then the `contextType` field will be set to that type, otherwise, it is omitted. 


Grammar: change 'immediately notified' to 'immediately notify' to correct the imperative form.

Suggested change

Desktop Agents MUST also immediately notified the apps that are listening to `contextCleared` event for this channel. If a `contextType` parameter was provided, then the `contextType` field will be set to that type, otherwise, it is omitted.

Desktop Agents MUST also immediately notify the apps that are listening to `contextCleared` event for this channel. If a `contextType` parameter was provided, then the `contextType` field will be set to that type, otherwise, it is omitted.

kriswest

Really really ready to see this merged, as I'm sure is @kemerava!

There's one small change needed to handle the null argument on addEventListener. Up to you if applying the same fix to DesktopAgentProxy's addEventListener - if not we need to raise an issue and another PR for that.

I've also suggested that EventListener is updated to take multiple types to simplify things when we have more events - technically there is only one of each type at present so null handling is just handling that one relevant type.

CHANGELOG.md

kriswest · 2025-07-22T17:03:42Z

packages/fdc3-agent-proxy/src/channels/DefaultChannel.ts

+    switch (type) {
+      case 'contextCleared':
+        listener = new EventListener(this.messaging, 'contextCleared', handler);
+        break;


Copilot has a point there. It looks like this is also wrong where we listener for the channelChanged event:

FDC3/packages/fdc3-agent-proxy/src/DesktopAgentProxy.ts

Lines 77 to 85 in d4a261a

addEventListener(type: FDC3EventTypes | null, handler: EventHandler): Promise<Listener> {

switch (type) {

case 'userChannelChanged':

return this.channels.addChannelChangedEventHandler(handler);

default:

Logger.warn(`Tried to add a listener for an unknown event type: ${type}`);

return Promise.reject(new Error('UnknownEventType'));

}

}

Co-pilot's suggestion to fix isn't right however. Rather EventListener will probbably ned to be adjusted to be able to take multiple types:

FDC3/packages/fdc3-agent-proxy/src/listeners/EventListener.ts

Line 12 in d4a261a

constructor(messaging: Messaging, type: string, handler: EventHandler) {

As we need to know the specific messages it should respond to (from a set that is wider than the scope of the listener).

packages/fdc3-standard/src/api/Channel.ts

robmoffat · 2025-07-24T14:13:34Z

packages/fdc3-agent-proxy/src/channels/DefaultChannel.ts

    await listener.register();
    return listener;
  }
+


we're going to need some cucumber tests for this otherwise you'll see the coverage dip!

robmoffat · 2025-07-24T14:14:25Z

packages/fdc3-agent-proxy/src/channels/DefaultChannel.ts

+    // first, ensure channel state is up-to-date
+    const request: ClearContextRequest = {
+      meta: this.messaging.createMeta(),
+      payload: {


Also, there will need to be support for this event added to the BroadcastHandler in the fdc3-web-impl, plus tests of the same there.

website/docs/api/conformance/App-Channel-Tests.md

website/docs/api/ref/Channel.md

hughtroeger · 2025-07-24T15:00:51Z

website/docs/api/spec.md

 A context type may also be associated with multiple intents. For example, an `fdc3.instrument` could be associated with `ViewChart`, `ViewNews`, `ViewAnalysis` or other intents.

-To raise an intent without a context, use the [`fdc3.nothing`](../context/ref/Nothing) context type. This type exists so that applications can explicitly declare that they support raising an intent without a context (when registering an `IntentHandler` or in an App Directory).
+To raise an intent without a context, use the [`fdc3.nothing`](../context/ref/Nothing) context type. This type exists so that applications can explicitly declare that they support raising an intent without a context (when registering an `IntentHandler` or in an App Directory). This type is also used when the context is cleared for the channel. If the optional context type is provided when performing [`clearContext`](ref/Channel.md#clearcontext), that type will be recorded in the field `subType` of [`fdc3.nothing`](../context/ref/Nothing) context type.


I'm unsure if this is still current. @kriswest indicated that the approach had been changed from using fdc3.nothing to the event based workflow. Is this still accurate?

Co-authored-by: Kris West <kris.west@interop.io>

…a/FDC3 into feature/context-clearing

Co-authored-by: Hugh Troeger <troeger.hugh@gmail.com>

kemerava · 2025-07-29T12:46:13Z

Merging to the new branch, will create another PR from that into main

Context Clearing

d9541d1

kemerava requested a review from a team as a code owner September 27, 2024 18:37

kriswest reviewed Oct 1, 2024

View reviewed changes

docs/api/ref/Channel.md Outdated Show resolved Hide resolved

kriswest reviewed Oct 1, 2024

View reviewed changes

docs/api/ref/Channel.md Outdated Show resolved Hide resolved

kriswest reviewed Oct 1, 2024

View reviewed changes

docs/api/ref/Channel.md Outdated Show resolved Hide resolved

kriswest reviewed Oct 1, 2024

View reviewed changes

kriswest added this to the 2.3 candidates milestone Oct 1, 2024

kemerava and others added 2 commits October 4, 2024 08:46

Apply suggestions from code review

77e2b61

Co-authored-by: Kris West <kris.west@interop.io>

Changelog and fixing the name of the field

a2c348e

kriswest reviewed Oct 8, 2024

View reviewed changes

kriswest added the needs-conformance-test label Oct 24, 2024

kemerava added 2 commits December 11, 2024 08:29

Merge remote-tracking branch 'origin/main' into feature/context-clearing

60456c3

Adding conformance tests

768f50d

kriswest requested changes Dec 13, 2024

View reviewed changes

kemerava and others added 2 commits January 31, 2025 11:56

Apply suggestions from code review

acac1a0

Co-authored-by: Kris West <kris.west@interop.io>

Merge remote-tracking branch 'origin/main' into feature/context-clearing

a4106fe

kriswest requested review from a team and kriswest April 17, 2025 15:32

Merge branch 'main' into feature/context-clearing

4e2bc61

kriswest mentioned this pull request Apr 24, 2025

Standard WG Meeting - April 24th, 2025 #1583

Closed

19 tasks

kemerava added 2 commits May 8, 2025 14:01

Merge remote-tracking branch 'origin/main' into feature/context-clearing

c66f420

Adding addEventListener for listening on clearing context

cdeea6a

Clearing context tests

1ad0c4a

kriswest mentioned this pull request Jun 19, 2025

FDC3 for Web Browsers & Bridging Discussion group - 19th June 2025 #1618

Closed

21 tasks

Making build pass

9c79048

kriswest mentioned this pull request Jun 26, 2025

Standard WG Meeting - June 26th, 2025 #1623

Closed

20 tasks

kriswest requested review from a team, Roaders and bingenito July 9, 2025 13:25

Merge remote-tracking branch 'origin/main' into feature/context-clearing

04507e0

bingenito requested a review from Copilot July 9, 2025 13:38

Copilot AI reviewed Jul 9, 2025

View reviewed changes

kemerava added 3 commits July 9, 2025 09:47

Adding the event for the contextCleared

e21ec30

npm

90c8fab

PR review changes

c63e1d4

kriswest mentioned this pull request Jul 18, 2025

FDC3 for Web Browsers & Bridging Discussion group - 17th July 2025 #1634

Closed

19 tasks

kriswest requested changes Jul 22, 2025

View reviewed changes

robmoffat reviewed Jul 24, 2025

View reviewed changes

packages/fdc3-standard/src/api/Channel.ts Outdated Show resolved Hide resolved

robmoffat reviewed Jul 24, 2025

View reviewed changes

hughtroeger reviewed Jul 24, 2025

View reviewed changes

kemerava and others added 7 commits July 25, 2025 12:46

Merge remote-tracking branch 'origin/main' into feature/context-clearing

b953954

Update CHANGELOG.md

bc5c98c

Co-authored-by: Kris West <kris.west@interop.io>

Merge branch 'feature/context-clearing' of https://github.com/kemerav…

c572444

…a/FDC3 into feature/context-clearing

Update website/docs/api/ref/Channel.md

90a06e3

Co-authored-by: Hugh Troeger <troeger.hugh@gmail.com>

Updating based on reviews

ac73c5c

Typo

6d22fb3

Update lang

a7e5c4b

kemerava changed the base branch from main to 1197-context-clearing July 29, 2025 12:44

kemerava merged commit 660182d into finos:1197-context-clearing Jul 29, 2025
6 of 7 checks passed

kemerava mentioned this pull request Jul 29, 2025

Context clearing (1197) #1642

Merged

17 tasks

kriswest mentioned this pull request Sep 24, 2025

Standard WG Meeting - September 25th, 2025 #1676

Closed

17 tasks

	: base(Fdc3EventType.ContextCleared, new Fdc3ContextClearedEvent(contextType))
	: base(Fdc3EventType.ContextCleared, new Fdc3ContextClearedEventDetails(contextType))

-        break;
+        break;
+      case null:
+        listener = new EventListener(this.messaging, 'allEvents', handler); // Register for all events
+        break;

	addEventListener(type: FDC3EventTypes \| null, handler: EventHandler): Promise<Listener> {
	switch (type) {
	case 'userChannelChanged':
	return this.channels.addChannelChangedEventHandler(handler);
	default:
	Logger.warn(`Tried to add a listener for an unknown event type: ${type}`);
	return Promise.reject(new Error('UnknownEventType'));
	}
	}

	Desktop Agents MUST also immediately notified the apps that are listening to `contextCleared` event for this channel. If a `contextType` parameter was provided, then the `contextType` field will be set to that type, otherwise, it is omitted.
	Desktop Agents MUST also immediately notify the apps that are listening to `contextCleared` event for this channel. If a `contextType` parameter was provided, then the `contextType` field will be set to that type, otherwise, it is omitted.

Conversation

kemerava commented Sep 27, 2024

Uh oh!

netlify bot commented Sep 27, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for fdc3 ready!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kriswest Oct 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kriswest left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kriswest left a comment

Choose a reason for hiding this comment

Uh oh!

kemerava commented Dec 13, 2024

Uh oh!

kriswest left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kriswest commented Apr 17, 2025

Uh oh!

kriswest commented Apr 17, 2025

Uh oh!

kemerava commented May 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Jul 9, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 9, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 9, 2025

Choose a reason for hiding this comment

Uh oh!

kriswest left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kemerava commented Jul 29, 2025

Uh oh!

netlify bot commented Sep 27, 2024 •

edited

Loading

kriswest Oct 8, 2024 •

edited

Loading

kemerava commented May 8, 2025 •

edited

Loading